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1.0 INTRODUCTION. 

1.1 CP/M OVERVIEW. 

Computers generally run a resident program 
called the Operating System (OS) that interprets 
the user's commands so that application programs 
can be run, files manipulated (with ERA, REN, 
PIP, for example) or disk information obtained 
(e.g., using DIR, STAT). In microcomputers, one 
standard operating system is called CP/M 
(Control Program/Monitor). CP/M and every other 
operating system use some method of determining 
which disk drive they are talking to, and which 
drives they can talk to. 

For HiNet, which supports CP/M and several 
other operating systems, the drive can be 
assigned to a local floppy disk or a partition 
on a HiNet Network Master or local Hard Disk. 
Generally, the OS keeps track with a mapping 
between LOGICAL and PHYSICAL devices. In CP/M 
the logical devices are the familiar 'drives A, 
B, C, D' as well as printer, paper reader/punch, 
and console device, depending upon the specific 
hardware in the computer system. 

CP/M keeps track of data on a disk in 
FILES. To the user, a file is just a program or 
a collection of data with a name. CP/M keeps 
track of files on a disk in a reserved space 
called the DIRECTORY. The directory contains all 
the information CP/M needs to be able to read 
from and write to each file. This information 
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includes pointers to the space on the disk that 
the file occupies. 

Space on a disk in GP/M is measured in 
logical blocks. The sizes of these blocks, which 
can be either Ik, 2k, 4k, 8k or 16k, are 
determined by the "Disk Parameter Block" (DPB). 
Hhe DPB values are generally not under the 
application program's or programmer's control. 
The BIOS programmer makes a DPB for each kind of 
disk and disk drive available as directed in 
Digital Research's CP/M documentation. 



1.2 DIRECTORIES AND FILE ALLOCATION 

When a logical drive is accessed for the 
first time (after warm or cold booting) CP/M 
scans the directory and makes a map of the 
blocks currently used by the files on the disk. 
This is called the ALLOCATION VECTOR (AV). The 
OS uses this vector to allocate new blocks to 
files when writing, and to de-allocate blocks 
when files are deleted. In CP/M it is kept in 
the BIOS, i.e., in high memory above the TPA 
(user program space) . 

CP/M's security for a drive is maintained by 
a method called checksums. A CHECKSUM VECTOR 
(CV) is computed when the Allocation Vector is 
computed. This vector consists of one byte for 
every 128-byte CP/M record of the directory. The 
byte contains the sum of all the bytes in the 
record. Whenever the directory is changed (e.g., 
when a file is erased, closed, or when a new 
file or extent is opened) the checksum byte is 
updated. 
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Whenever a record of the directory is 
accessed/ the corresponding checksum byte is 
recalculated. If the newly calculated value 
doesn't match the old value in the vector, the 
drive is set to R/0. CP/M thinks that the disk 
has been changed without it being notified, and 
tries to keep the user from destroying data by 
not allowing any writes until the checksums 
agree again. 

As an example, consider two people using 
the same partition on the same hard disk at the 
same time. If user A changes information in the 
directory (say by ERA or PIP) the user's 
checksum vector will be updated properly. But 
the checksum vector in user B's memory will not 
be updated. The next time user B reads that part 
of the directory, the checksum byte for that 
record will not agree and he will get a "BDOS 
R/0 ERROR". This is one problem with sharing. 

There is also a variation on the previous 
problem. If user A allocates a block to a file, 
user B's OS does not know about it because only 
user A's Allocation Vector is updated. User B's 
OS could allocate the same block and overwrite 
user A's data. In this case, data is lost with 
no warning to the users, since the Operating 
Systems do not detect any error. 



1.3 SHARING PARTITIONS 

To enable more than one person to use a 
CP/M disk at the same time, a method must be 
devised so that when one person makes a change 
to the directory or the Allocation Vector (AV), 
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everyone will know. The method DMS chose puts 
the AV on the disk instead of in the BIOS for 
shared partitions. Each user's OS knows (by 
virtue of a flag in the ALLOC table) that the 
drive is shared. Whenever the directory or the 
AV is to be updated, the user's OS locks the 
partition (via a HiNet BIOS lock command) so 
that it has sole access to the drive. Then it 
does its updating and when finished unlocks the 
partition so that another user can make changes 
if he or she wants to. In this way blocks are 
not allocated to more than one= file and the 
directory is always kept up to date. Any user 
can read when the drive is locked, but only the 
person who has locked the drive can write to it. 

HIDOS allows more than one person to work in 
the same partition at the same time but NOT on 
the same file . When working on a file, CP/M 
keeps in local memory a copy of the directory 
entry (in the form of a File Control Block), and 
modifies this copy as changes are made to the 
file (changes meaning adding or erasing blocks). 
The changes are not reflected in the directory 
until the file is closed, or a new extent is 
needed. 

Since a local copy is kept by CP/M, the 
locking mechanism used above will not work. In 
fact, it is extremely impractical for any 
distributed- processor CP/M network to take care 
of this situation on the OS level. It would, of 
course, be desirable for the OS to take care of 
everything so that existing software could run 
with no modifications. 
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WHY THE OPERATING SYSTEM CAN'T LOCK RECORDS. 

To show that it is impractical for the OS 
to provide for record locking, we will give some 
examples to illustrate the problem. If we assume 
the OS is totally responsible for locking and 
unlocking records, then the OS needs some rule to 
follow. 

The OS does not know if a record needs to 
be locked when it is read. Thus every record 
read must be locked. This is not efficient, 
since many times a read will be to examine a 
record only. If no updating is involved there is 
no need to lock the record. 

Assuming every read requires a lock, let 
User A and User B work on the same file in the 
same partition. User A reads and then locks a 
record X. When User B wants to read record X his 
OS would realize that the record was locked and 
could: 

• ignore it and read it anyway, 

• return without reading, 

• return telling program record is locked, 

• wait until read is granted. 

The first two choices are obviously 
unacceptable. The third choice brings out a CP/M 
problem. The only values CP/M returns after a 
read are and 1 , representing either success or 
a failure (error). Therefore, in this case all 
the OS could do is report a failure to the User. 
If the program checks for this kind of error it 
will probably abort the program — an unacceptable 
result. 
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The fourth case leaves User B hang irq while 
waiting for the record to be unlocked. How long 
will User B have to wait? The problem becomes — 
when does the OS unlock the record? Several 
options are available: 

• wait until another record is read by the same 
user, 

• wait until that record is written back by the 
same user, 

• wait for the file containing the record to be 
closed, 

• wait until the user logs out. 

We cannot expect that the user's program 
can tell the OS anything about the status of the 
record since we are assuming in these cases that 
the OS is totally responsible. 

The last three options can be dismissed as 
impractical since: 

• User A may never log out. 

• He may never close the file since he may have 
only read from it. 

• He may also never write that record back for 
the same reason. 

The first option is also not acceptable but 
for a different reason. User programs can have 
logical records of almost any size. The OS, 
however, deals with a set record size. The OS 
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only knows of that record size and can thus only 
lock records of the length it knows about. 

This leads to a real problem. If the user's 
logical record size is bigger than the OS's 
record size^ all of the user- requested record 
may not be locked. For example^ let the user's 
record size be a 2-Kbyte chunk in some database, 
and the OS's record size be 128 bytes. When the 
user's program requests to read a 2K record , the 
OS will lock each 128-byte record as it is read, 
UNLOCKING the last 128-byte record it locked. 
Thus only the last 128 bytes of the 2K chunk 
remains locked. 

A similar problem occurs when the user's 
record size is not an even divisor of the OS's 
record size. The user's records will generally 
go across the OS record boundaries. Therefore 
the OS will lock only one of the OS records 
needed to lock all of the user's record. 



1.5 APPLICATION PROGRAMS & RECORD LOCKING 

The solution to these problems is for the 
application program to do record locking and 
unlocking. The HiNet BIOS provides a locking 
/unlocking mechanism for this purpose. 

The application program is designed to 
determine when a record needs to be locked, and 
when it can be unlocked. The program must avoid 
typical locking problems (like mutual lockout — 
when two programs have each locked records the 
other needs). The user program MUST do its own 
locking/unlocking to share a file or records. 



Release: 1/1/84 



DMS HIDOS PROGRAMMERS MANUAL 2.0 USING HIDOS 



2.0 USING HIDOS—LIMITS AND RESTRICTIONS. 

Important! Do not use these BIOS calls on a 
shared partition: 



Home 


SetDma 


SelDisk 


Read 


SetTrk 


Write 


SetSec 


SecTran 



Only use BOOS calls for Reads and Writes! 

It is permissible to use DMS extended BIOS 
calls with the exception of SendNet and RecNet. 
If you are using HiNet commands with SendNet or 
RecNet, be sure you understand how HIDOS and 
HiNet work. 

Do NOT change DPB's since HIDOS has special 
entries in the DPB that are non-standard. 

Do NOT allow more than one person to use or 
modify a file at the same time. The application 
program that manipulates a file can allow this 
if it does some kind of locking on the records 
or file during read/modify/write routines. If 
the application program does not explicitly do 
locking then do not share files. Also, take care 
that no one is using a file in a shared partition 
when that file is erased by another user. 

It is a good idea to establish a method for 
identifying files so that those people working 
on the same shared partition will not confuse 
their files with someone else's. If it is 
desired that more than one person have access to 
the same files, use the NetLock/NetUnLock 
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Utilities or some other method to avoid more 
than one person working on the same file at the 
same time. Always use the filename for the 
lockstring, rather than a shared partition name. 

WZyEeNING In a shared partition^ do not use 

any program that creates a temporary file of a 
fixed name. If two people are using such a 
program, the temporary files will get confused 
with disastrous results. For example, many 
compilers and word processors create temporary 
files of a fixed name. (WORDSTAR creates a 
temporary file called EDBACKUP.$$$ for every 
large file that is opened for editing or 
reading.) You will probably need to experiment 
or talk to the program manufacturer to be sure 
of this. 

Directory information is volatile for 
shared disks. When a 'DIR' is done, remember 
that the information is instantly 'old' 
and may be incorrect. Someone else may have 
modified the directory information immediately 
after you asked to get it. Thus, files may 
disappear even though they were there for a 
'DIR'. Therefore, you must make sure that your 
files are only used by you (you could use the 
NetLock/NetUnlock ut i 1 i t i es) . 

Disk space usage information may not be 
correct. To get the most up-to-the-minute 
information on how much space is left on the 
disk, do a warm boot first. Remember, between 
the time you warm boot and a program such as 
STAT checks the disk space usage, someone else 
working in that partition could have changed the 
value without your local computer knowing about it. 
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Another point to watch: if a file is 
written to but is never closed, the directory 
will not show that the blocks allocated for the 
writes are used. They will, however, be 
allocated in the shared Allocation Vector on the 
disk since every block allocation is 'instantly' 
reflected in the shared Allocation Vector on the 
disk. Therefore there is unusable space on the 
disk. This leads to erroneous disk space 
information from programs such as STAT. You can 
run SHRALLOC to clean this up (see section 5.0). 



3.0 HINET LOCKSTRINGS AND NETLOCK 

Hi Net NETLOCK is a warning device that 
tells the User if the partition or file in 
question is already being updated. This is a 
User-dependent system for file security. 

Each User, before updating files in a 
shared partition, enters the lockstring 
sequence — NETLOCK filename— to secure a file. 
The Master checks to see if the lockstring is 
already in the NETLOCK Table. If it isn't then 
the lock is granted. 

If the filename lockstring is already in 
the NETLOCK Table then the message **This file 
or partition is locked is displayed. The User 
must then wait until the lockstring is accepted 
when he or she resubmits it. 

NETLOCK will not prevent a User from 
writing to a f i le that is locked. It is a 
warning only. 
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To unlock a file after updating it, the 
User enters the command NETUNLOK filename. The 
lockstring for the filename is removed from the 
Network's NETLOCK Table. 

NOTE NETLOCK lockstrings must be the name 

of the specific file being updated. Do not use 
HIDOS shared partition names for lockstrings. 

HIDOS uses a similar method of lockstrings 
when it updates the Allocation Vector and the 
Directory; see the following section. 



4.0 PROGRAMMING TECHNIQUES UNDER HIDOS 

HIDOS is a modified version of the CP/M 2.2 
BDOS and it essentially works in the same way. 
These modifications allow shared access to hard 
disk partitions. It is up to the transient 
program to do file and/or record locking as is 
necessary for the application. 

When sharing a disk^ the directory and the 
Allocation Vector must be kept accurate and up 
to date for all users. Whenever a BDOS function 
that modifies either of these is called^ the 
local HIDOS does a HiNet lock over the network 
to the master. The HIDOS lockstring is the name 
of the partition. The OS will wait for access if 
the partition is locked. It should not have to 
wait for long since no HIIX)S lock can last for 
longer than a BDOS function call. When the BDOS 
function is finished the partition is unlocked. 

The directory and the Allocation Vector are 
both on the disk. Whenever either of these needs 
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to be changed, it is read in from the disk, 
modifiedr and written back. This is all done 
under the protection of the HIDOS lock* In this 
way the data on the disk is always up to date. 

In shared partitions, the Allocation Vector 
is stored in the first block after the 
directory. A file with the name of the partition 
followed by an exclamation point (1) is created 
with the block containing the Allocation Vector 
allocated to it. The file is stored under CP/M 
User 15. The file serves only as protection for 
the Allocation Vector and as a flag that the 
Allocation Vector was set up on the disk. 

The local OS can tell that a partition is 
shared by checking a bit in the control byte of 
the hard disk's allocation table maintained by 
the systefn utility ALLOC. The byte is stored as 
part of the DPB in the BIOS. Whenever a disk is 
logged in, the local HIDOS checks to see if the 
disk is shared. 

The BDOS functions that modify the 
directory are: Open, Close, Delete, Make, 
Rename, Set File Attributes, Read/Write 
Sequential/Random (when closir^ an extent and/or 
opening a new extent). The BDOS functions that 
modify the Allocation Vector are Delete and 
Write Sequential/Random. 

When the Allocation Vector is needed for 
allocation or deallocation it is read in from 
the disk using parameters from the 'DMS DPB' 
into the Allocation Vector space in the BIOS. 
When the BDOS is done with the modification the 
Allocation Vector is written back to the disk 
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before unlocking and returning from the BDOS 
call. The DMS DPB is an extended CP/M DPB. 

HIDOS uses a directory high water mark 
different from the CP/M high water mark. In 
CP/M, when a disk is logged in (i.e./ first 
accessed after a warm or cold boot) the entire 
directory is scanned. During this time the 
Allocation Vector and Checksum Vector are 
computed and initialized. At the same time, an 
internal variable is set to the last used entry 
in the directory, and this entry is the CP/M 
high water mark. If a file by the name of 
$$$.SUB is found, the appropriate flag is 
returned to the CCP to indicate there is a 
submit file to be run. Various internal 
variables are set up as well. 

In HIDOS shared partitions , the high water 
mark is kept in the directory. It is set up by 
the system utility COMPRESS. An E8 hex is put in 
the entry following the last used entry, and is 
always kept up to date. The CP/M high water mark 
can only go up. However, the HIDOS high water 
mark goes up and down as necessary. 

When a shared disk is logged in under HIDOS 
(first accessed after a warm or cold boot) the 
directory does not need to be scanned since the 
Allocation Vector is already set up and stored 
on the disk. The checksum vector security is not 
used on shared partitions since changes are 
expected to occur. The high water mark is 
already set up. The result of these changes is 
that shared HIDOS partitions boot very quickly. 
COMPRESS also compresses the directory so that 
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directory searches execute much quicker than 
on normal CP/M partitions. 

NOTE- — Since the directory is not scanned 
at every warm or cold boot, SUBMIT files cannot 
be run on shared partitions. 



5.0 SHARED PARTITION MAINTENANCE 

Periodically CX)MPRESS and SHRALLOC should be 
run in a shared partition. 

COMPRESS will compress the directory which, 
through normal use, aquires many gaps in it. 

SHRALLOC will recompute the Allocation 
Vector and get rid of any discrepancies between 
the directory and the allocation vector. 

Discrepancies can occur if a program writes 
to the disk but does not close the file. The 
blocks allocated to the file by the writes are 
reflected in the Allocation Vector but not in 
the directory. Thus, even though the blocks are 
not used, they cannot be re-allocated. 

NOTE— -The file PARTITION -NAME.! stores 
the allocation vector on the disk for each 
partition. If this file is missing when SHRALLOC 
is run, a warning message is displayed. The 
partition must then be changed from shared to 
non-shared in the ALLOC Table. SHRALLOC can then 
be run to restore the Allocation Vector; the 
partition can then be marked as shared again in 
the ALLOC Table. 
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When SHRALLOC is run it creates and then 
deletes a temporary file called TEMPFILE. If 
something goes wrong during the program's 
execution this file will be visible in the 
directory. 

WARNING \lhen running COHFRESS and SHRMIXX: 

you must make sure that no one else is using the 
partition. 

NOTE— The next release of HINET/HIDOS will 
replace SHRALIXC with an automatic function in 
the ALLOC Table program. When a partition is 
marked as shared in the ALLOC Table^ the 
Allocation Vector will be created at that time 
by ALLOC. COMPRESS will still be available to 
periodically clean up the directory. 



6.0 FILE AND RECORD LOCKING 

The idea behind file and record locking is 
to allow more than one person the ability to 
access and modify the same data at the same 
time^ with each person getting the most recent 
data. In order to assure that you always have 
the most recent data, you need to do a "read" 
knowing that no one else has accessed the data 
file or record with the intention of modifying 
it. The procedure is to get ownership of the 
right to update the data (LOCK the data in 
question), read it, modify it, write it back, 
and then release ownership so another person can 
gain ownership. Read access without locking 
could always be granted with the understanding 
that someone else may be currently modifying 
what you have read. 
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As an example, consider an airline 
reservation system. The operator does unlocked 
reads to check seating availability. When the 
customer agrees to an available seat, the 
operator does a lock, then a read and checks to 
make sure the seat is still available—since 
someone else may have taken it between the time 
he or she did the unlocked read and the locked 
read. If still available, the operator reserves 
the seat by updating the record with that data, 
writing it back and unlocking the record. 

If everyone only did locked reads, system 
performance would greatly suffer with people 
waiting for access to be granted for their locks 
before they could read or examine data. Such 
waiting is not necessary since most reads don't 
need to be locked. 



6.1 RECORD LOCKING PROCEDURES 

It is important to realize that you must 
reread any data that is to be modified before 
locking/modification/writing since what you have 
read without locking may not be current. Someone 
else may be changing the data while you are 
examining it. 

You should develop a method for naming what 
needs to be locked. The file name is fine for 
file locking; for records the filename and 
record number combined could be a good name. 

The HiNet locking mechanism locks a string 
of, at most, 13 bytes. See section 6.4 for 
examples of its use in CBASIC and Z80 Assembler. 
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To update a record, follow these 
procedures: lock, or wait for the lock to be 
granted, read the record, update it, write it 
back, and unlock it. If the record does not 
exist (i.e., it is not yet there to read) skip 
the read step. Probably some initialization 
should be done to the record. The method of 
determining if the record is there or not is 
application-dependent. For some applications 
all records can be allocated initially. For 
others, only extension may be allowed so that 
all allocated records are contiguous. 

To extend a file you need to know which 
record is the current end. A specific record 
(say the first) can hold a pointer to the end. 
In this case, lock the record with the pointer. 
Using a random write (or sequential, if 
appropriate) write the record after the last 
record. This becomes the new last record, so 
update the pointer. Write the pointer record 
back to the disk. Unlock the record with the 
pointer. 



6.2 DATA RECORD SIZE VS. CP/M RECORD SIZE 

The logical record size equals the data 
record size and the application program record 
size. Complications can arise if the logical 
record size to be locked is not the same size 
as, or is not a multiple of, the CP/M record 
size (128 decimal, 80 hex bytes). It is highly 
recommended that the data record size be 128 
bytes or an integer multiple of 128. The problem 
is that a CP/M record can contain parts of more 
than one logical record. Thus the logical record 
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can be locked, but not the CP/M record. 
Therefore, more than one person can have the 
CP/M record in CP/M memory, each thinking he or 
she has sole ownership to modify that record. 
When they write back the logical record, that 
part of the CP/M record corresponding to some 
other logical record will be set to what it was 
when the read was done, overwriting any changes 
someone else may have made. 

If you decide that you want a logical 
record size which is not equal to an integral 
number of CP/M records, you must lock the CP/M 
records, i.e., use the CP/M record name(s) that 
are being used by more than one logical record. 
There will be one or two records to lock. 

Let us consider these four aspects of the 
problem: 

1. The data record is much smaller than the CP/M 
record. 

2. The data record is slightly smaller than the 
CP/M record. 

3. The data record is much larger than the CP/M 
record. 

4. The data record is slightly larger than the 
CP/M record. 

Example 1. The data record is much smaller than 
the CP/M record. 
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CP/M records ...'r', 's', 't',... 



s I t j 

)( 9 )(| 10 )( 11 )( 12 )(| 



I )( 5 )( 6 ){ |7 )( 

logical records ... 5, 6^ 1, 8, 9, 10^ 11, 12,... 

If logical record 6 is locked, read, 
changed, written back, and unlocked by user A, 
and at the same time User B locks, reads, 
changes and writes back logical record 5, the 
last one to write will overwrite the previous 
user's change. This occurs because the same CP/M 
record "r" is read and written each time. 

Example 2. The data record is slightly smaller 
than the CP/M record. 

CP/M records ... 'c', 'd', 'e', 'f, 'g',... 



_+ + — 

I 

)( 4 )( 5 



7 )( 



)( 3 



)( 



)( 



logical records ...3, 4, 5, 6, 7,... 

The same problem exists as in #1. Notice 
this time that the logical record generally 
crosses a f^ysical record boundary. 
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Example 3. The data record is much larger than 
the CP/M record. 

CP/M records ...'j', 'k', 'l', 'm', 'n', 'o',... 



k I 1 



)( 


17 




)( 


18 





) ( 



logical records ...17^ |8r... 

In this case if user A works on logical 
record 17 and user B on logical record 18 the 
conflict arises in CP/M record 'm'. 

Example 4. The data record is slightly larger 
than the CP/M record. 

CP/M records ...'j', 'k', '1', 'm', 'n', 'o',... 

I j I k I 1 I m I n I o I 



)( 7 



)( 8 



) ( 9 



)( 



10 )( 



11 )( 



logical records ...7, 8, 9, 10, 11,... 

The same situation as #3 occurs here, only 
now almost all the CP/M records are shared by 
two logical records (except CP/M record Jo' 
which is totally contained in logical record 11, 
so no problem there). 
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6.3 CALCULATION OF CP/M RECORDS USED BY 
LOGICAL RECORDS 

Given a logical record we need to find the 
CP/M records that must be locked to avoid 
logical record conflict. There are one or two 
CP/M records in each of the four cases. The 
procedure is to find the CP/M records used by 
the first and last bytes of the logical record. 
We assume that the logical records are logically 
continuous and linearly numbered (i.e., records 
are numbered 2,3,4,5...). 

To find the CP/M record used by the last 
byte of the logical record, first get the 
logical record number. If the first logical 
record is record "0" then add one to the logical 
record number. Now multiply this number by the 
logical record size and then divide by the CP/M 
record size (128 decimal). If there is a 
remainder, round up. The result is the CP/M 
record the END of the logical record uses. 

Now, to find the CP/M record used by the 
beginning of the logical record, repeat the 
above procedure for the logical record just 
before the CP/M record. In this case, before 
dividing by the CP/M record length, add one so 
that the first byte of tfie logical record in 
question will be included. 

These two records are the ones to lock. If 
they are the same record then only one record 
needs to be locked. If locking two CP/M records, 
watch out for lock-out. If you lock one record 
and the other is locked, unlock the first, wait 
a random amount of time and retry, since you may 
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be competing with someone else for the same 
records. 

It is assumed that all CP/M records between 
the first and last CP/M records of the logical 
record do not need to be locked since anyone 
wanting to read them must also lock the ends. 
This assumes no overlap of logical records. 

If the logical data file has something other 
than logical records (such as a file header or 
record headers ) then the size of this must be 
taken into account. 

EXAMPLES 

1: Logical file name = DBASE! 

logical record size = 136 bytes 

logical records = 1,2,3,4,5, 

(Note: first record=l ) 



no headers or inter record info. 

Want to lock logical record 23. 

(23 * 136) /128 =24.44 — -> 25 
( (22 * 136) +1 ) / 128 =23.38 > 24 

So lock 24 and 25. Lockstrings could be DBASE24 
and DBASE25. 



Logical file name = DBASEl 
logical record size =136 bytes 
logical records =0,1,2,3,4,5,..; 

(Note: first record=0) 
no headers or inter record info. 
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Want to lock logical record 23. 

( (23+1) * 136 ) / 128 = 25.5 > 26 

( [(22+1) * 136] + 1 ) / 128 = 24.44 > 25 

So lock 25 and 26. Lockstrings could be DBASE25 
and DBASE26. 



3: Logical file name = DBASEl 

logical record size = 136 bytes 
logical records = 1 ,2^3,4, 5^. .. . 

(Note: first record=l ) 
Assume there is a 32-byte file header before 
logical record 1. 

Want to lock logical record 75. 

[(75 * 136) + 32] / 128 = 79.9 ~> 80 
{[(74 * 136) +32] + 1} / 128 = 78.88 — > 79 

So lock 80 and 79. Lockstrings could be DBASE79 
and DBASE80. 

4: Logical file name = SMALLDATA 

logical record size = 18 bytes 

logical records = 1,2^3,4... 

(Note: first record=l ) 

Assume no headers or inter-record data. 

Want to lock logical record 345. 

(345 * 18) / 128 = 48.5 — > 49 
{(344 * 18) + 1 } / 128 = 48.3 ~> 49 

So lock 49. Lockstring could be SMALLDATA49. 
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6.4 HINET BIOS LOCK AND UNLOCK 

Record lcx:king and unlocking are invoked by 
first constructing a "lockstring" and then 
calling a BIOS lock or unlock entry point. The 
lockstring should indicate the file and record 
to be locked. Note that the lockstring can, in 
fact, contain any sequence of bytes. However, to 
allow different applications to utilize record 
locking on the same HiNet system requires that a 
convention be established. The recommended 
convention is to use the file name as the first 
8 characters and the record number as the last 5 
characters of the lock string. 

The addresses of the BIOS lock and unlock 
entry points need to be calculated at program 
run time. The entry points are addresses in the 
Digital Microsystem extended BIOS jump table.The 
addresses are calculated as follows: 

BIOS Lock 

1. Get the address of the standard BIOS warm 
boot jump. This is kept at locations 1 and 2. 

2. Add 93 ( 5d hex ) to the warm boot address. 
This is the offset to the lock function. 

3. The result is the address of the BIOS lock 
entry point. 

BIOS Unlock 

1 . Get the address of the standard BIOS warm 
boot jump. This is kept at locations 1 and 2. 
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2. Add 99 ( 63 hex ) to the warm boot address. 
This is the offset to the unlock function. 

3. The result is the address of the BIOS unlock 
entry point. 

Before calling the BIOS lock or unlock 
entry points, locations 74 (4A hex) and 75 (4B 
hex) should point to the lockstring, i.e., 
contain the address of the string to be locked. 
The first byte of the string is an integer from 
1 to 13, indicating the length of the string. 

The BIOS routines return immediately and 
put the outcome of the request in location 73 
(49 hex). This is the status of the request. 



Lock Request 



Returned Status 



Meaning 

Lock accepted. The lockstring 
was entered into the master 
lockstring table. 

Lock denied. The lockstring 
is already in the table, 
i.e. the string is 
already locked. 

Lock table full, or string 
length byte is bad 
(= or > 13). 
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Unlock Request 

Returned Status Meaning 

Unlcxrk accepted. String 

was found in master 
lockstring table and removed. 

2 Unlock failed. String was 

not found in master 
lockstring table, or 
string length byte is bad 
(= or > 13). 

The CBASIC functions "fn.lock" and 
"fn.unlock" can be used to interface with the 
lock and unlock routines in the BIOS. Similar 
interface functions can easily be written for 
other compilers. 

DEF FN.L0CKWORK%(STRING$,FUNC%) 
ADDR% = SADD(STRING$) 
HIGH% = (ADDRl/lOOh) AND OFFh 
IF ADDR% < THEN HIGH% = HIGH% - 1 
POKE 4AH,ADDR% AND OFFH 
POKE 4BH,HIGH% 

CALL ((PEEK(2)*100h) OR PEEK (1)) + FUNC% 
FN.L0CKWORK% = PEEK(49H) 
RETURN 
FEND 

DEF FN.LOCK%(STRING$) 

FN . LOCK% = FN . L0CKWORK% (STRING$ , SDH ) 

RETURN 
FEND 
DEF FN. UNLOCK! (STRING?) 
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FN.UNLOCK% = FN.LOCKWORK%(STRING$,63H) 
RETURN 
FEND 

The following program demonstrates how to 
use the record locking functions. First, a file 
containing 128 records is created. Several users 
can then simultaneously run this program, and 
update different records in the file at will. 
The program will allow only one user at a time 
to update any particular record; however, 
several users are allowed to update DIFFERENT 
records in the file simultaneously. The lock 
functions are on the "LOCKFNS.BAS" file. 

The statement "READ #1,R;" is needed after 
a write to force CBASIC to flush its I/O buffer 
for file number 1. Without this statement, the 
record will not be updated on the disk until the 
next random read or write to that file. This is 
due to a peculiarity in the I/O algorithms used 
by CBASIC. Similar problems may be encountered 
with other compilers. 

%INCLUDE LOCKFNS 

F1LENAME$ = "DEMO. DAT" 

INPUT "ENTER TO CREATE, 1 TO 

UPDATE DEMO FILE"; I 
IF I = THEN \ 

CREATE FILENAME? RBCL 1 28 AS 1 :\ 

FOR I = 1 TO 128 :\ 

PRINT #1;I :\ 

NEXT I :\ 

CLOSE 1 
OPEN FILENAME? RBCL 128 AS 1 
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TOO INPUT "RECORD NUMBER" ;R 

LOCKSTRING$ = "DEMO "+STR$ (R) 
WHILE FN.LOCK%(LOCKSTRING$) <> 

WEND 
READ #1,R;I 
PRINT "OLD VALUE";! 
INPUT "NEW VALUE"; I 
PRINT #1^R;I 

READ #1^R; REM flush the record 
1% = FN.UNLOCK%(LOCKSTRING$) 
GO TO 100 
END 
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TDL Z80 CP/M DISK ASSEMBLER VERSION 2.21 



PAGE t 



0100 



; The following is a z80 assembly program in TDL 
;mna(nonics. It shows how to compute the address of and 
;use the BIOS netlock/netunlock functions. 

.pabs 

.phex 

.loc lOOh 



0000 
0005 
0009 
OOOD 
OOOA 

004A 

0049 

0000 
0001 
0002 



wboot 
bdos 

print == 
cr == 
If 




5 

9 

ODh 

OAh 


locAddr == 


4Ah 


locStat == 


49h 


locAccept == 





locDeny == 


1 


locReject = 


2 



; address of lock string 

;BIOS lock status returned 
;as set below 

;lock or unlock is accepted 

;lock request, string exists 

; if lock, then table full or 
;lockstring length = or > 1 3 
; if unlock, then string not in 
; table or lockstring length = 
;or > 13. 



005D 



locOffset == 5Dh ;Offset from standard BIOS jump 
; table (warm boot jump) into 
;Digital Microsystem's extended 
;BIOS jump table to the net lock 
;call. 



0063 



unlocOffset == 63h 



;Offset from standard BIOS jump 
; table (warm boot jump) into 
;Digital Microsystem's extended 
;BIOS jump table to the netunlock 
;call. 



0100 




Start: 








0100 


FB 




ei 




; for 2dt 


0101 


31 0186 




Ixi 


sp, stack 


; set up stack 


0104 


CD 01 ID 




call 


Lock 


; try to lock 


0107 


CD 01 3B 




call 


UnLock 


; try to unlock 


01 OA 


C3 0000 




jmp 


wboot 


; exit via warm boot 
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PAGE 2 



01 OD 




NetLock 








01 OD 


2A 0001 




Ihld 


wboot + 1 


; Address of standard 
;BIOS jump table 


0110 


11 005D 




ixi 


D, IcjcOf f set 


; Offset into DMS 
; extended BIOS jump 
; table 


0113 


19 




dad 


D 


; HL = address of DMS 
;netlock call. 


0114 


E9 




pchl 







0115 
0115 

01 1 8 

one 
one 



2A 0001 
11 0063 

19 
E9 



NetUnLock: 

Ihld 



Ixi 



dad 



pchl 



wboot + 1 



D,unlocOffset 



; Address of standard 
;BIOS jump table 
; Offset into DMS 
; ex tended BIOS jun^ 
? table 

; HL = address of DMS 
;netunlock call. 



Try to lock string 'locString*. 



OllD 


Lock: 




01 ID 


21 0278 


Ixi 


H, locString 


0120 


22 004A 


shld 


locAddr 


0123 


CD 01 OD 


call 


NetLock 


0126 


3A 0049 


Ida 


locStat 


0129 


FEOO 


cpi 


locAccept 


01 2B 


CA 0154 


jz 


IkGranted 


01 2E 


FEOl 


cpi 


locDeny 


0130 


CA 0159 


jz 


locked 


0133 


FE02 


cpi 


loc Reject 


0135 


CA 01 5E 


jz 


tableFull 


0138 


C3 01 6D 


jmp 


lockError 



; Set up address of 
; string to lock. 

;Ask master lock string 

; Get returned status 
; Was lock granted? 



; Is lockstring already 
;in master's table? 

; Was lock rejected? 
; String length bad 
;or lock table is full. 

; If none of above, 
;HiNet error. 
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Try to unlock string 'locString'. 



0133 
01 38 
01 3E 


UnLock: 

21 0278 Ixi 

22 004A shld 


H, locString 
locAddr 


; Set up address of 
; string to lock. 


0141 


CD 0115 


call 


NetUnLock 


; Ask master to unlock 
; locString 


0144 
0147 
0149 


3A 0049 
FEOO 
CA 0163 


Ida 
cpi 
jz 


locStat 
loc Accept 
unLkGranted 


; Get returned status 
; Was unlock granted? 


01 4C 
01 4E 


FE02 
CA 0168 


cpi 
jz 


loc Reject 
notLocked 


; Was unlock rejected? 
; String length bad 
;or locString not in 
; table, i.e. locString 
;is not locked. 



0151 



C3 01 6D 



jnp 



lock Error 



; If none of above, 
;HiNet error. 



0154 
0154 
0157 


11 0186 
1817 


IkGranted: 
Ixi 
jmpr 


D,locOkMsg 
PrintMsg 


0159 
0159 
01 5C 


11 0196 
1812 


locked: 

Ixi 
jmpr 


D,lcx:kdMsg 
PrintMsg 


01 5E 
01 5E 
0161 


11 OIBF 
180D 


tableFull: 
Ixi 
jmpr 


D,fullTableMsg 
PrintMsg 


0163 
0163 
0166 


11 0205 
1808 


unLkGranted : 
Ixi 
jmpr 


D,unLkOkMsg 
PrintMsg 


0168 
0168 
01 6B 


11 0217 
1 803 


notLocked: 
Ixi 
jmpr 


D,notInTable 
PrintMsg 


01 6D 
01 6D 


11 0269 


lockError: 
Ixi 


D,netErrMsg 


0170 
0170 


0E09 


PrintMsg: 

mvi 


C, print 
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0172 
0175 



CD 0005 
C9 



call 
ret 



bdos 



0176 
01 7E 
0186 

0186 

0196 

OlAD 

01 BF 
01 D3 
01 EC 
0202 

0205 

0217 
0234 
0250 
0266 



767676767676 
767676767676 



.byte 
.byte 



4C6F636B2067 

4C6F636B2064 

61 6C726561 64 

4C6F636B2064 
6C6F636B7374 
206F72206261 
0D0A24 

556E6C6F636B 

556E6C6F636B 
20696E206D61 
206F72206261 
0D0A24 



stack: 

IcxrOkMsg: 

lockdMsg: 

fullTableMsg: 



unlkOkMsg: 
notlnTable: 



0269 48694E657420 netErrMsg: 



76h, 76h, 76h, 76h, 76h, 76h, 76h, 76h 
76h , 76h , 76h , 76h , 76h , 76h , 76h , 76h 



.ascii 'Lcxrk granted.' [cr] [Ifl '$• 

.ascii 'Lock denied, locString ' 

.ascii 'already locked.' [cr J [If] '$' 

.ascii 'Lock denied, master ' 

.ascii 'lockstcing table is full,' 

.ascii ' or bad string length.' 

.ascii [crl[lf]'$' 

•ascii 'Unlock granted. ' [cr] [If] '$' 

.ascii 'Unlock failure, locString not' 

.ascii • in master lockstring table,' 

.ascii ' or bad string length.' 

.ascii [cr][lf]'$' 

.ascii 'HiNet error.' [cr] [If] '$' 



0278 
0279 



OD locString: 
4F7572444261 



.end 



+++++ sy^BOL table +++++ 



.byte 13 

•ascii 'OurDBasel2345' 



BDOS 


0005 


CR OOOD 


FULLTA 01 BF 


LF 


OOOA 


LKGRAN 


0154 


LOCAOC 0000 


LOCAOD 004A 


LOCDEN 


0001 


LOCK 


OllD 


LOCKDM 0196 


LOCKED 0159 


LOCKER 


01 6D 


LOGOFF 


005D 


LOOOKM 0186 


LOCREJ 0002 


LUCSTA 


0049 


LOCSTR 


0278 


NETERR 0269 


NETLOC 01 OD 


NETUNL 


0115 


NOTIWr 


0217 


NOTLOC 0168 


PRINT 0009 


PRINTM 


0170 


STACK 


01 86 


START 01 00 


TABLEF 01 5E 


UNLKGR 


0163 


UNLKOK 


0205 


UNLOCK 01 3B 


UNLOOO 0063 


WBOOT 


0000 


.BLNK. 


. 0000:03 X 


.DATA. 0000* ; 


K .PROG. 0000' 


X 
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6.5 NETWORK BUFFER OSAGE 

The HiNet BIOS normally provides a Ik 
network buffer to enhance system performance. 
However, for some programs such as multi-user 
data bases, data must not be buffered or 
obsolete data may mistakenly be taken as 
current. 

In the past, programs that had to ensure 
that all data was current would first read 
(unwanted) data into the Ik buffer so that the 
read of desired data would come across the 
network and not from the Ik buffer. This is 
neither elegant or efficient. Starting with the 
HiNet BIOS version 247 there is a DMS-specific 
BIOS jump vector (SetNetMode) that allows a 
transient (i.e., user) program to select the 
network buffer usage mode. The three buffer 
modes are: 

0) Always use the Ik network buffer. This 
is the default mode; it is automati- 
cally selected after a cold or warm 
boot. 

1 ) Do not use the buffer contents on the 
next NetRead request - force a network 
transmission to ensure current data. 
This will replace the Ik network buffer 
contents; all subsequent NetReads will 
use the buffer contents. 

2) Do not use the buffer contents until a 
cold or warm boot or until the program 
changes the network buffer usage mode. 
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The SetNet Mode jump vector is available in 
both the network Master and the network Stations 
but will result in a Call Error on a stand-alone 
system. Since the network Master never has the 
Ik network buffer, the SetNetMode jump vector 
will do nothing - it is there simply so that 
networking programs do not have to check to see 
if they are running on a Master or Station. 

To call the SetNetMode vector perform the 
following steps: 

1) Load locations 0001 and 0002. This is 
the address of the warm boot vector. 

2) Add the of f set of the DMS-specific jump 
table to the offset of the network 
function that is to be accessed and 
move the value into register DE. 

3) Add the value of register DE to the 
contents of register HL. 

4) Load register C with the desired mode: 

=> always use the network buffer 

1 => don't use the network buffer the 

next time only 

2 => never use the network buffer 

5) Execute the code at the address 
obtained in step 2. 
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The previous NetMate value is returned in 
register A in case you wish to restore the 
NetMode to its previous state. 

Reproduced below is a tested assembly 
program fragment that sets the NetBuf Mode to 
Buffer Mode 1, "Do not use the Ik buffer for the 
next NetRead only". 

.ident netjmp 

.pabs 

.phex 

.loc lOOh 

This prograiT\ tests code which is to be included 
in the HiDos programmer's guide. 



BiosVector = 
DMSoffset 
Netmodedisp = 
NotNextTime = 

Ihld 
Ixi 

dad 
mvi 
pchl 



01 h ;CP/M W B jump address 

(5Dh-3) ; First jump in I>IS table 

(15*3) ;# of jumps to SetNetMode 

01 ; Direct read next time 

BiosVector ;CR^ warm boot 
D , EHSo f f se t+Ne tmoded i sp 

;# of bytes to SetNetMode 
D ;HL = addr of code in bios 
C, NotNextTime ; direct read next time 

; execute it, return to 

; calling routine 



.END 



At system assembly time, the choice may be 
made to not include the Ik network buffer in the 
system at all; this will automatically ensure 
that all NetRead requests get current data from 
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the network. This generally provides poorer 
performance than when using the network buffer 
in conjunction with the SetNetMode vector. The 
distribution versions of the HiNet bios all use 
the network buffer for the stations. If the 
HiNet BIOS is assembled without the network 
buffer then the SetNetMode vector is still 
present but does nothing. 



Release: 1/1/84 36 



DMS-HIDOS PROGRAMMERS MANUAL 



INDEX 



Alloc Flag, 12 
Allocation Vector, 2 

Changing, 12 

location, 12 

Shared Partitions, 3 
BDOS Functions 

Modify Directory, 12 
BDOS Lockstrings, 12 
BIOS Calls 

Shared Partitions, 8 

Warnings, 8 
BIOS Jump Vector 

SetNetMode, 33 
Checksum 

HIDOS, 13 
Checksum Vector, 2 
COMPRESS, 13 
COMPRESS utility, 14 
Directory High Water Mark, 13 
Disk Parameter Block, 2 
DPB Sizes, 2 
Drives 

Write Security, 2 
Extending Files, 17 
File Control Block, 4 
HIDOS 

Checksum, 13 
HIDOS High Water Mark, 13 
HIDOS Mechanics, 11 
High Water Mark 

Updating, 13 
Lockstrings 

BDOS, 11 



Release: 1/1/84 I-l 



DMS-HIDOS PRCX5RAMMERS MANUAL 



Modifications to CP/M 2.2, 11 
Network Buffer, 33 

Modes, 33 
Record Locking 

procedure, 17 
Record Sizes 

Calculating, 18 

CP/M, 18 

Logical, 18 

Physical, 18 
Record/File Locking, 12 
Shared Partition Flag, 12 
SHRALLOC, 13, 14 
Warm Boot 

HIDOS, 13 



Release: 1/1/84 1-2 



